Theme Manager Notes
===================


Theme Directories
-----------------

Individual Themes are stored as standard directories. The name of the directory (e.g. 'Steel') is the name of the Theme. A Theme Directory contains the following:

- an Icons spritefile;
- a Tools spritefile;
- a Choices textfile.

The Icons and Tools files replace the default set used by the Desktop. The Icons file may contain the following:

- replacements for the standard set of Wimp icons (as included in the OS ROM);
- replacement icons for non-ADFS discs (such as IDEFS);
- replacement icons for the Application Suite.

ThemeMan will make an effort to deal sensibly with these categories of icons when switching between themes. If you include more icons in your Icons file (such as new icons for third-party applications), you may need to restart to see the full effects of your changes.

The Choices file is used to set options controlling how the Desktop draws windows, icons, etc. It consists of a series of lines in a similar format to Message files (i.e. Token:Expansion). The first four lines should be consistent in every theme. This allows the author to add details on who created the Theme, the date it was created, and any Notes on usage (e.g. if it needs a high-colour display, or only works on a certain OS version). This information is readable by the user in !ThemeMan. An example file might be:

Name:NewTheme
Author:Mr Bloggs
Date:12th January 2007
Notes:Needs RISC OS Select 3i3 or later - won't run on RISC OS 5.

Other tokens are optional. In general, due to the way RISC OS the RISC OS commands work, omitting a token will lead to the feature (e.g., 3D borders for windows) being *un-set* (i.e., the parameter is not simply ignored). This means that it's better in general to have a complete set of commands to ensure your theme looks as consistent as possible.


Choices options
---------------

These are the current commands and their expansions. Commands relating to Buttons and Groups are only activated when used on Select. Commands suffixed with an asterisk are only activated on Wimps >5.00 from Castle/ROOL.

<string> = String value
<Yes> = 'Yes' turns the feature on, any other value off
<Hex> = Six-figure colour value in RRGGBB Hex notation

Name:<String>		Theme name
Author:<String>		Theme Author
Version:<String>	Theme Version
Notes:<String>		Accompanying Notes

DesktopIcons:<Yes>	An Icons file is present in the Theme
WinTools:<Yes>		A Tools file is present in the Theme

DesktopFontBlend:<Yes>	Specifies whether to use font blending
RemoveIconBoxes:<Yes>	Removes boxes around the text in filer windows

3DSettings:<Yes>	Windows and Menus have 3D borders
WinOutline:<Hex>	Window Outline Colour*
WinOverwrite:<Yes>	Outline is drawn over Tool icons*
WinHighlight:<Hex>	Colour value for Window highlight
WinShade:<Hex>		Colour value for Window shade
MenuHighlight:<Hex>	Colour value for Menu highlight
MenuShade:<Hex>		Colour value for Menu shade

WinTextured:<Yes>	Windows have background textures
MenuTextured:<Yes>	Menus have background textures
MenuDifferent:<Yes>	Menus use a different texture

ButtonSpecial:<Yes>     Turns button-colouring on
ButtonColour:<Hex>      Colour value for Button face
ButtonDefColour:<Hex>   Colour value for Default Button face
ButtonFade:<Yes>        Buttons have a fade effect applied
ButtonRim:<Yes>         Buttons have a thin rim

GroupColour:<Hex>       Colour value for Groups

BorderThin:<Yes>	Gadgets are drawn with thin borders
BorderSpriteIcons:<Yes>	Apply effects to sprite-only icons too

Note on Fonts: The specifier string should be the name of one of the fonts supplied in the ROM (e.g. Homerton.Medium), or 'System font'. There is currently no facility to use non-ROM fonts.


Technical Notes
---------------

These commands are used to set-up the corresponding switches in IconSprites, ToolSprites, WimpVisualFlags and WimpIconBorder. Window textures are controlled by OS_Byte 162 as no switch exists in WimpVisualFlags.

Currently the full range of switches in WimpIconBorder is not supported. The document IconSettings lists which features are implemented. It should be easy to add more, depending on demand (personally, I think the rounded border options are very poorly done in the OS, and I'm unlikely to add a blend option for information fields until there's a corresponding option to set the background colour).


Chris Wraight
2008

